file-loader

What is file-loader?

The file-loader npm package is used to process files such as images, fonts, and other binary assets within a webpack build process. It can copy files to the output directory and resolve import/require() on a file into a url.

What are file-loader's main functionalities?

Importing Images

Allows importing image files directly in JavaScript or TypeScript files. The file-loader processes the import and replaces it with the final path to the output file.

import img from './file.png';

Configuring Output Path and Filenames

Configures webpack to output files with a specific naming pattern and to a specific directory. It also allows setting a public path for the files when they are referenced in the browser.

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: '[path][name].[ext]',
              outputPath: 'images/',
              publicPath: 'assets/',
            },
          },
        ],
      },
    ],
  },
};

Handling Fonts

Enables the inclusion and processing of font files in various formats. The file-loader will handle these assets and output them to a specified directory.

module.exports = {
  module: {
    rules: [
      {
        test: /\.(woff|woff2|eot|ttf|otf)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: '[name].[ext]',
              outputPath: 'fonts/',
            },
          },
        ],
      },
    ],
  },
};

Other packages similar to file-loader

url-loader

The url-loader works like the file-loader, but can return a Data URL if the file is smaller than a byte limit. This can reduce the number of HTTP requests for small files.

raw-loader

The raw-loader allows importing files as a string. This is useful for importing things like HTML or SVG directly into your JavaScript code, which is different from file-loader's typical binary asset handling.

copy-webpack-plugin

This plugin allows copying individual files or entire directories to the build directory. It is more flexible than file-loader for simply copying files without processing them through webpack's module system.

README

file-loader

A file loader module for webpack

Requirements

This module requires a minimum of Node v6.9.0 and works with Webpack v3 and Webpack v4.

Getting Started

To begin, you'll need to install file-loader:

$ npm install file-loader --save-dev

Import (or require) the target file(s) in one of the bundle's files:

// bundle file
import img from './file.png'

Then add the loader to your webpack config. For example:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/,
        use: [
          {
            loader: 'file-loader',
            options: {}
          }
        ]
      }
    ]
  }
}

And run webpack via your preferred method. This will emit file.png as a file in the output directory (with the specified naming convention, if options are specified to do so) and returns the public URI of the file.

Note: By default the filename of the resulting file is the MD5 hash of the file's contents with the original extension of the required resource.

Options

context

Type: String Default: context

Specifies a custom file context.

// webpack.config.js
...
{
  loader: 'file-loader',
  options: {
    name: '[path][name].[ext]',
    context: ''
  }
}
...

emitFile

Type: Boolean Default: true

If true, emits a file (writes a file to the filesystem). If false, the loader will return a public URI but will not emit the file. It is often useful to disable this option for server-side packages.

// bundle file
import img from './file.png'

// webpack.config.js
...
{
  loader: 'file-loader',
  options: {
    emitFile: false
  }
}
...

name

Type: String|Function Default: '[hash].[ext]'

Specifies a custom filename template for the target file(s) using the query parameter name. For example, to copy a file from your context directory into the output directory retaining the full directory structure, you might use:

// webpack.config.js
{
  loader: 'file-loader',
  options: {
    name: '[path][name].[ext]'
  }
}

Or using a Function:

// webpack.config.js
...
{
  loader: 'file-loader',
  options: {
    name (file) {
      if (env === 'development') {
        return '[path][name].[ext]'
      }

      return '[hash].[ext]'
    }
  }
}
...

Note: By default the path and name you specify will output the file in that same directory, and will also use the same URI path to access the file.

outputPath

Type: String|Function Default: undefined

Specify a filesystem path where the target file(s) will be placed.

// webpack.config.js
...
{
  loader: 'file-loader',
  options: {
    name: '[path][name].[ext]',
    outputPath: 'images/'
  }
}
...

publicPath

Type: String|Function Default: __webpack_public_path__

Specifies a custom public path for the target file(s).

// webpack.config.js
...
{
  loader: 'file-loader',
  options: {
    name: '[path][name].[ext]',
    publicPath: 'assets/'
  }
}
...

regExp

Type: RegExp Default: undefined

Specifies a Regular Expression to one or many parts of the target file path. The capture groups can be reused in the name property using [N] placeholder.

import img from './customer01/file.png'

webpack.config.js

{
  loader: 'file-loader',
  options: {
    regExp: /\/([a-z0-9]+)\/[a-z0-9]+\.png$/,
    name: '[1]-[name].[ext]'
  }
}

Note: If [0] is used, it will be replaced by the entire tested string, whereas [1] will contain the first capturing parenthesis of your regex and so on...

useRelativePath

Type: Boolean Default: false

Specifies whether or not to generate a relative URI for each target file context.

// webpack.config.js
{
  loader: 'file-loader',
  options: {
    useRelativePath: process.env.NODE_ENV === "production"
  }
}

Placeholders

[ext]

Type: String Default: file.extname

The file extension of the target file/resource.

[hash]

Type: String Default: 'md5'

Specifies the hash method to use for hashing the file content. See Hashes.

[N]

Type: String Default: undefined

The n-th match obtained from matching the current file name against the regExp

[name]

Type: String Default: file.basename

The basename of the file/resource.

[path]

Type: String Default: file.dirname

The path of the resource relative to the webpack/config context.

Hashes

Custom hashes can be used by specifying a hash with the following format: [<hashType>:hash:<digestType>:<length>].

digestType

Type: String Default: 'hex'

The digest that the hash function should use. Valid values include: base26, base32, base36, base49, base52, base58, base62, base64, and hex.

hashType

Type: String Default: 'md5'

The type of hash that the has function should use. Valid values include: md5, sha1, sha256, and sha512.

length

Type: Number Default: 9999

Users may also specify a length for the computed hash.

Examples

The following examples show how one might use file-loader and what the result would be.

// bundle file
import png from 'image.png'

// webpack.config.js
{
  loader: 'file-loader',
  options: {
    name: 'dirname/[hash].[ext]'
  }
}

# result
dirname/0dcbbaa701328ae351f.png

---

// webpack.config.js
{
  loader: 'file-loader',
  options: {
    name: '[sha512:hash:base64:7].[ext]'
  }
}

# result
gdyb21L.png

---

// bundle file
import png from 'path/to/file.png'

// webpack.config.js
{
  loader: 'file-loader',
  options: {
    name: '[path][name].[ext]?[hash]'
  }
}

# result
path/to/file.png?e43b20c069c4a01867c31e98cbce33c9

Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

CONTRIBUTING

License

MIT

Changelog

2.0.0 (2018-08-21)

Code Refactoring

• defaults: update to latest webpack-defaults (#268) (687f422)

BREAKING CHANGES

• defaults: Enforces engines of "node": ">=6.9.0 < 7.0.0 || >= 8.9.0"

<a name="1.1.11"></a>